Repository navigation
docs: re-baseline the SDK contract to dsh 0.2.2-rc.1 - #28
Merged
Merged
Conversation
…rc.1 Restate both frozen specs from the T1 re-verification at dsh-v0.2.2-rc.1 (66491b05e3), keeping every earlier table and dated amendment as history. Wire spec: eight upstream request methods and six notifications, with the crate still sending exactly six and a session/query row marked NOT sent; the two new notification names and the subagent.started origin narrowing; fact corrections for the seven turn/end kinds, Python run() -> session/query, TypeScript finishReason, and the additive optional config fields; new section 7.7 for the session/prompt divergence; decided non-goals for session/query, approval/request, and user-question/ask; new re-baseline table and re-verification anchor. Launch spec: re-anchor section 2.1 to the shipped-profile registry and the first-use self-init, re-anchor initialize.cwd consumption, record the Node >=24.9.0 install bound, and add the new re-baseline table and re-verification anchor.
…e facts CI: move the keyless-runtime-handshake pin to @deepseek-ai/[email protected] at all three textual sites (npm cache key, install command, fail-loud message) and rewrite the rationale for tag dsh-v0.2.2-rc.1 (66491b05e3, 2026-11-04): eight upstream request methods with the crate still sending six, six notifications with four modelled, session/query, approval/request, and user-question/ask deliberately unwrapped, and session.event.event still an untyped Value. The setup-node step notes the runtime's >=24.9.0 floor; no Node major bump was needed. Rustdoc: session/resume records that the initialized route replaces the restored session's stored model selection and that a stored reasoning effort survives only on a matching provider and model (server.ts:574-590 at the tag). The session-tree module and the subscription doc record that subagent.started is emitted only for subagent-origin sessions, so an ordinary fork adds no edge. README pair: replace the false "four server-to-client notifications" claim with the six-declared/four-modelled statement, name the two unmodelled notifications and the subagent-origin emission rule in both languages, and re-record both blob hashes in README.i18n.yaml.
…rgence Fix the six consolidated plan-QC findings on the docs surfaces only: - README pair: TypeScript's RunResult does carry the field, camelCase-named `finishReason: string | null`; the crate still follows Python's snake_case five-field set. - README pair + `Session::run` rustdoc: the run step sequence follows Python but the crate posts `session/prompt`, so a leading `/` is prompt text and `session.query.completed` is never consumed (wire spec §7.7). - README pair: bring-your-own runtime Node floor `>= 24.9.0` (npm CLI only; the wheel carries its own Node) with the upstream citation. - Wire §6.1/§7.2: the runtime emits client-directed requests only to a client that opts in at `initialize`; this crate never opts in and answers `-32601`. - Wire §6.1 and launch §6.1: split the additive-option paragraph so `reasoningEffort`/`maxTokens` are the already-supported `initialize` fields, and only the question/approval options gate the §8 non-goals. README.i18n.yaml re-recorded from `git hash-object README.md README.zh.md`.
✅ Verdict:
|
| Findings | Count |
|---|---|
| 🔴 must-fix | 0 |
| 🟠 should-fix | 0 |
| 🟡 may-fix | 4 |
| 🔵 nit | 2 |
| ❓ unverified | 10 |
📋 Review
Findings
🟡 New verified-versions table contradicts the crate's current release notes about which runtime CI verifies
- Evidence:
- Evidence:
README.md:70— new row asserts0.2.2-rc.1is verified by "CI keyless handshake";.github/workflows/ci.yml:103does pin@deepseek-ai/[email protected], so the README row is correct. ButCHANGELOG.md:8(the newest release section's### Changedbullet) still tells consumers "The CI keyless-runtime-handshake job now verifies the npm route against@deepseek-ai/[email protected]". A reader taking either artifact gets a different answer for the same gate. - Impact: The README change establishes a consumer-facing claim about what CI verifies, but the shipped release notes for the same release state a different runtime pin. One of the two artifacts lies to consumers; without the fix, the contradiction ships in the same release tarball (both
README.mdandCHANGELOG.mdare package-included). - Effort: XS — one bullet line in
CHANGELOG.md(or its unreleased fragment path) re-pinned to0.2.2-rc.1. - Risk: LOW — prose only; no code or gates touched, and
ci.yml:103is the already-verified source of truth. - Confidence: HIGH (opened
README.md:61-85,CHANGELOG.md:8,ci.yml:99-119). - Merge class: may-fix (documentation surface — capped here regardless of impact; the prose content is wrong on the CHANGELOG side and the README is the artifact that exposes it).
- Fix sketch: Re-pin the CHANGELOG bullet (or the
dsh-0.2.2-rc1-realignmentfragment) to0.2.2-rc.1so the release notes and this new table agree; no README text change needed.
- Evidence:
- Location:
README.md:61-85 - Category: DOCS
- Merge class: may-fix
🟡 Table asserts keyless-handshake verification for 0.2.1-rc.2–rc.5 that no repo artifact records
- Evidence:
- Evidence:
README.md:63-64— the section definition promises "Each release below was checked two ways: a keyless handshake … and a reading of the upstream SDK-facing surface at the release tag".README.md:71-74— rows for0.2.1-rc.5,rc.4,rc.3,rc.2are markedverifiedfor that handshake. A repo-wide search for those versions yields hits only inREADME.md/README.zh.md: no CI job exercises them (ci.yml:103pins only0.2.2-rc.1), no.mstar/specs/or.mstar/knowledge/record rebaselines atdsh-v0.2.1-rc.2…rc.5, and the changelog/fragments mention only0.2.1-rc.1and0.2.2-rc.1(.changes/unreleased/dsh-runtime-baseline-0.2.1-rc.1.md:4). - Impact: Four of the six rows state a completed two-stage verification whose evidence exists nowhere in the repository, so a consumer cannot reproduce or audit the claim — exactly the failure mode the project's own guidance forbids for report-derived facts (
.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md:52: "A report-derived fact stays an open question until it is verified, and the docs must say so"). - Effort: S — re-run/re-record the handshake for those four installs, or relabel/remove the rows.
- Risk: LOW — documentation only; no behavior changes. Removing a row slightly narrows the advertised compatible set.
- Confidence: MED — the absence of any record is proven by search; I could not read the upstream release tags (no network) to prove the handshakes never happened.
- Merge class: may-fix (documentation surface with unverifiable claims; not merge-blocking).
- Fix sketch: Either record the verification artifacts those rows imply (handshake run + surface diff per tag), or state explicitly that the rows are best-effort reads of the upstream surface rather than handshakes.
- Evidence:
- Location:
README.md:63-74 - Category: DOCS
- Merge class: may-fix
🔵 Status column in the new table carries no information
- Evidence:
- Evidence:
README.md:68-75— every row has the identicalStatusvalueverified, while the adjacent prose already defines membership ("Each release below was checked…" / "Releases outside this table are unverified"). - Impact: One column of repeated noise in both README sides; adds width on narrow viewers and a second place to keep in sync if a status value ever changes.
- Effort: XS — drop the
Statuscolumn from both tables. - Risk: LOW — cosmetic; the surrounding sentences already carry the same semantics.
- Confidence: HIGH (opened the table rows).
- Merge class: nit.
- Fix sketch: Delete the
Statuscolumn from the English and Chinese tables; keepRuntime+Verified by.
- Evidence:
- Location:
README.md:68-75 - Category: DOCS
- Merge class: nit
🟡 PR ships no .changes/unreleased/ fragment although the repo's CI gate requires one
- Evidence:
- Evidence:
README.zh.md:56-77— the new### 已验证的运行时版本section is a user-facing documentation change;AGENTS.md:36-37— "Every PR that changes user-visible behavior ships a changelog fragment in the same PR:.changes/unreleased/<slug>.md" and "CI enforces this on PRs";.github/workflows/ci.yml:146-186— jobchanges(name: changelog fragment) runs on everypull_request(nopaths-ignore) and exits 1 whengit diff --name-only ${BASE}...HEAD -- '.changes/unreleased/'is empty after excluding.gitkeep/README.md. The recon diffstat for this PR isREADME.i18n.yaml,README.md,README.zh.mdonly — no fragment. - Impact: the
changelog fragmentcheck fails mechanically on this PR regardless of the text being correct; the section also introduces no release note for the newly published compatibility promise. - Effort: XS
- Risk: LOW — adding one fragment cannot change crate behavior; only the fragment's
category:choice needs judgement (AddedvsChanged). - Confidence: HIGH (read
AGENTS.md, the CI job body, and the PR diffstat). - Merge class: may-fix
- Fix sketch: add
.changes/unreleased/<slug>.md(format perdocs/release.md) withcategory: AddedorChangedand one English bullet stating that the README pair now publishes the verified-runtime table. Documentation surface — tracked, not a ship-stopper.
- Evidence:
- Location:
README.zh.md:56-77 - Category: docs
- Merge class: may-fix
🟡 Verified-runtime table claims per-tag audits that the repository cannot substantiate, and drops a previously recorded verification
- Evidence:
- Evidence:
README.zh.md:58-68— the section promises every row passed two checks ("下表中的每个版本都经过两项检查") and rows0.2.1-rc.2…rc.5each assert无密钥握手;dsh-v0.2.1-rc.X 的 SDK 表面差异审计. A repo-wide search for0.2.1-rc.[2345]matches onlyREADME.md:71-74andREADME.zh.md:65-68. The contract SSOT records re-verification only at two anchors:.mstar/specs/dsh-runtime-launch-contract.md:262(dsh-v0.2.1-rc.1, 2026-10-17) and:274(dsh-v0.2.2-rc.1, 2026-11-06);.mstar/specs/dsh-sdk-wire-parity-surface.md:17likewise only atdsh-v0.2.2-rc.1..github/workflows/ci.yml:103pins only@deepseek-ai/[email protected].CHANGELOG.md:8records the last npm-route verification against@deepseek-ai/[email protected]— a release the new table omits and therefore now marks "未经验证" perREADME.zh.md:75-77. - Impact: the table is read as a compatibility guarantee (it is the only place telling a consumer which runtime to pin). Four of its six rows have no reproducible evidence in the tree, and one verification the repo itself recorded (0.1.7-rc.1) is silently contradicted by the blanket "releases outside this table are unverified" sentence.
- Effort: S
- Risk: LOW — text-only change inside the README pair; the sibling
README.mdrows andREADME.i18n.yamlhash must move together (AGENTS.md:42-43). - Confidence: MED (absence of in-repo records is strong; the audits may have happened in PR/CI history I cannot read).
- Merge class: may-fix
- Fix sketch: keep only rows whose verification is recorded, or add a date + spec/report pointer to each row's 验证方式 cell; reconcile the 0.1.7-rc.1 statement so the pair does not declare a verified release unverified. Documentation surface — register it, do not gate the merge on it.
- Evidence:
- Location:
README.zh.md:65-68 - Category: docs
- Merge class: may-fix
🔵 Upstream release tags cited as bare strings instead of the official-repo citation the h2 rule requires
- Evidence:
- Evidence:
README.zh.md:64-69— every 验证方式 cell cites a bare tag (dsh-v0.2.2-rc.1,dsh-v0.2.1-rc.5, …) with no link;AGENTS.md:45— "Upstream DSH references only viahttps://github.com/deepseek-ai/deepseek-harness(citation rule); no local filesystem paths in either README." - Impact: a reader cannot follow a row's evidence to the upstream tag, and the pair drifts from the repo's stated citation form (the same cells also name
.github/workflows/ci.yml, which is a repo-relative path and therefore in bounds). - Effort: XS
- Risk: LOW — link-only edit; the pair and the recorded blob hashes must be updated together.
- Confidence: MED (the rule's intent is upstream citations; a bare tag is a judgement call, not a proven breach).
- Merge class: nit
- Fix sketch: link each tag to
https://github.com/deepseek-ai/deepseek-harness/tree/<tag>, or cite the tag once under the intro paragraph with a single link, keeping EN and ZH rows identical.
- Evidence:
- Location:
README.zh.md:64-69 - Category: docs
- Merge class: nit
Revalidated findings
Reassessed 0/14 prior finding(s) this round · 14 invalid-output · 0 omitted · 0 over cap · 14 recheckable · context coverage: complete
| finding | disposition | evidence | thread |
|---|---|---|---|
| Launch spec §4.2/§5 still cite the frozen-basis sessions-root lines while §10's tag note records the moved location | unverifiable (invalid-output) | - | - |
| Launch spec §2.2.3 forbids two of the three dump subcommands its own §2.1 enumerates | unverifiable (invalid-output) | - | - |
| Node floor is stated once, with an unqualified upstream path, and not at the npm route it constrains | unverifiable (invalid-output) | - | - |
New CI provenance guard silently no-ops when npm prefix -g yields nothing |
unverifiable (invalid-output) | - | - |
This changeset trips its own changelog-fragment gate; CI changes job will fail as submitted |
unverifiable (invalid-output) | - | - |
| Rewritten keyless-guard comment is accurate — no claim needs correction (checked, rejected candidate) | unverifiable (invalid-output) | - | - |
README divergence inventory omits the newly documented session/prompt vs session/query divergence |
unverifiable (invalid-output) | - | - |
| Launch spec §2.2 carries unmarked frozen-basis line citations next to §2.1's re-anchored ones | unverifiable (invalid-output) | - | - |
| Knowledge doc still asserts a single upstream pin that both specs have since re-baselined past | unverifiable (invalid-output) | - | - |
Partial re-baseline leaves dsh-v0.2.1-rc.1 anchors in the same doc comments the PR re-tagged |
unverifiable (invalid-output) | - | - |
Docs/CI-comment change ships with no .changes/unreleased fragment, so the changelog fragment job fails on this PR |
unverifiable (invalid-output) | - | - |
git diff ... || true can turn a diff-computation failure into the release-prep exemption |
unverifiable (invalid-output) | - | - |
The two normative specs cite different upstream lines for Python's initialize_timeout_seconds on the same re-baseline |
unverifiable (invalid-output) | - | - |
| Wire spec §2's method inventory and its §9 assertion disagree about which methods exist | unverifiable (invalid-output) | - | - |
Linked-issue AC
none
✅ Verified
none
🗑️ Considered & rejected
none
🛠️ Plan to fix
none
The READMEs named no runtime version at all, leaving readers to guess which @deepseek-ai/dsh releases the crate was checked against. Add one section, right after the Node-floor prerequisites, listing 0.2.1-rc.1..rc.5 and 0.2.2-rc.1 with the check each one passed: keyless handshake (crate boots the runtime, initialize completes, close reaps the child) plus a reading of the upstream SDK-facing surface at the release tag. Each row is a fact with its method; the six-method, unknown-tolerant wire contract explains why additive upstream changes pass through, and versions outside the table are marked unverified. Re-record README.i18n.yaml with the new blob hashes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Re-baselines the crate's verified-runtime contract from
@deepseek-ai/[email protected]todsh-v0.2.2-rc.1and moves the CI keyless-handshake pin.The audit conclusion that drove this change: the crate's implementation is already wire-compatible with 0.2.2-rc.1 and needs no code change. Upstream kept every request method and parameter the crate sends,
session/promptstill enqueues verbatim, the four modelled notifications keep their payloads,SESSION_FORMAT_VERSIONstays 4, andContentBlockMapkeeps its seven members. What did change is the documented baseline and two documented behaviors, plus the crate's own re-verification rule ("if upstream advances past the pinned ref, re-run the greps before restating any line").What changed
wire-parity-surface,runtime-launch-contract): eight declared request methods with the crate still sending six; six declared notifications with four modelled;session/query/approval/request/user-question/askrecorded as decided non-goals;subagent.startednarrowed to subagent-origin sessions; resumed sessions take the initialized model route; new§7.7records therun()routing divergence; earlier citation tables preserved append-only.0.2.2-rc.1. The resolve step now also asserts the resolved binary lives under$(npm prefix -g)/bin, so a preinstalleddshearlier on PATH cannot satisfy the guard.src/api.rs; origin gate insrc/client/session_tree.rs/src/client/core.rs.RunResult.finishReasonfact, the leading-/prompt semantics, the opt-in client-directed request qualification, and the runtime Node>= 24.9.0floor.README.i18n.yamlre-recorded..changes/unreleased/dsh-0.2.2-rc1-realignment.md).Verification
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo build --all-targets && cargo test— 197 tests passed, 0 failed.66491b05e3: 29 wire rows (27 PASS / 2 FAIL-fact) + 22 launch rows (20 PASS / 2 FAIL-moved);Changed rules: none.README.i18n.yamlblob hashes matchgit hash-objecton both sides.Non-goals
No new request method, notification parser, public API, dependency, or runtime behavior. The three unwrapped upstream capabilities are recorded as deliberate decisions, not gaps.